home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource5 / 304_01 / roff5.doc < prev    next >
Text File  |  1990-02-14  |  47KB  |  1,314 lines
  1. August 29, 1989
  2.  
  3.             ROFF5, V2.00
  4.  
  5.            by Ernest E. Bergmann
  6.                      730 Seneca Street
  7.             Bethlehem, PA 18015
  8.  
  9.  
  10.     ROFF5 is a major revision of my earlier formatter,
  11. ROFF4, v1.61.  It has been written in Turbo C, v2.0 (MS-DOS)
  12. for greater portability.  It has many significant extensions.
  13. However, some of the old commands have been changed in order
  14. to more closely align with the venerable formatters: nroff
  15. and troff.  Many of the exceptions are due to the influence of
  16. WORDSTAR [tm by MicroPro] or personal taste.
  17.  
  18.     ROFF4 is an expanded version of ROFF, based on the
  19. formatter in Kernighan and Plauger's book SOFTWARE TOOLS, is
  20. written in BDS C, and employs the directed i/o functions
  21. that go along with that package.  Well, half of the directed
  22. I/O anyway - it doesn't use redirected input because more
  23. than one file can be used as input for a run.  So that some
  24. of the input files may be used to "set-up" the formatter for
  25. a particular style and for particular hardware.  It is
  26. possible to substitute keyboard input instead of files for
  27. educational and test purposes.
  28.  
  29.     ROFF was provided by Neal Somos for the public
  30. domain via the BDS 'C' Users' Group's volume, CUG -- "Just
  31. Like Mom's".  Some of this documentation started there as
  32. well.
  33.  
  34.     This formatter contains features important for the
  35. preparation of technical manuscripts.  Special symbols or
  36. fonts that can be defined by or for the user can be produced
  37. (if the hardware is capable!).  Super and subscripts can be
  38. handled as well as backspace even for printers without
  39. reverse scrolling or backspacing hardware capabilities.
  40. However, the output device should recognize separately the
  41. <CR> and <LF> functions.  
  42.  
  43.     Because of the strong similarity to the nroff and troff of
  44. UNIX[R by AT&T], documentation of those formatters would be relevent
  45. here.  In particular, I recommend the paperback book, "troff
  46. Typesetting for UNIX[TM] Systems," by S. L. Emerson and K. Paulsell,
  47. ISBM 0-13-930959-4.  I have tried to avoid using command names that
  48. are inconsistent with troff, but I have not strictly followed the
  49. same conventions because I place a higher premium on longer names
  50. for ease of documentation and I want to directly drive simple
  51. devices such as a variety of dot matrix printers with special
  52. symbols that are sometimes needed in technical manuscripts.  I have
  53. personally used ROFF4 and ROFF5 for dozens of manuscripts.  I have
  54. thus located and fixed bugs and determined features that appeared to
  55. make sense.
  56.  
  57. "Preprocessor" files and directives can be used to merge
  58. stock phrases, boiler plate, make macro definitions, automate
  59. numbering, and create diversions (for footnotes, table of
  60. contents, etc.)
  61.  
  62.     To support the capabilities of WORDSTAR[tm by
  63. MicroPro] extended underlining, strikeout, and multiple
  64. strike capability are provided as well.
  65.  
  66.  
  67. -----------------------------------------------------------------
  68.  
  69. The MS-DOS version uses the curly-bracket character '}'
  70. to redirect output, and only one target may be
  71. specified.   Thus:
  72.  
  73. a>roff5 filename1 filename2 }outfile
  74.  
  75. would format filename1 and filename2 and write the output
  76. on a file "outfile" on the default drive. If there is no
  77. target specified, the default output is the console.
  78.  
  79. The more conventional character '>' is not used because
  80. MS-DOS 2.x intercepts any '>' or '<' on the command
  81. line and redirects all output to the specified target,
  82. even output which the program  addressed to 'stderr'. 
  83.  
  84. _________________________________________________________________
  85.  
  86. A>roff5 -s -f filename1 filename2 -f -m -r -i -g -*
  87.  
  88.     The option, -s, causes the formatter to stop (pause)
  89.     at the start of each page of output; the bell at the
  90.     console is sounded (if it exists!) and the program
  91.     waits until any key is pressed at the console.  It
  92.     is essential for printers that are feed single sheets
  93.     at a time!
  94.  
  95.     An option that was not shown above, -o[page or range],
  96.     is used to selectively generate output of ONLY certain
  97.     pages.  It is useful to retype pages that got "eaten"
  98.     by the printer (Henry Harpending's aptly put language).
  99.     To retype only page 23, say, make the option: -o23
  100.     To retype pages 23 through 29 use: -o23-29
  101.     To retype pages 23 to the end use: -23-
  102.     These options changes the values of the internal
  103.     variables, FIRSTPAGE and LASTPAGE which originally
  104.     have the values of 1 and 30000, respectively.  Normally
  105.     this option would be placed early enough in the
  106.     command line that no pages have been printed yet.
  107.  
  108.     Another option that was not shown above, -n[page#],
  109.     is used to change the default starting page number.
  110.  
  111.     The option, -f, would introduce a formfeed (0CH)
  112.     into the output stream (useful for placing blank
  113.     pages, or aligning printer pages) where it appears;
  114.     in this example, before the first page of output,
  115.     and, again, at the very end of the output.
  116.  
  117.     The option, -m, causes a list of macro definitions
  118.     to be typed to the console.  It is a useful tool for
  119.     debugging complex macro packages where the 
  120.     preprocessor's expansions are too subtle for humans.
  121.  
  122.     The option, -i, causes a list of string insertions
  123.     to be typed to the console.  Useful for macro writers,
  124.     as was the -m, described above.  Also, for noting
  125.     what are the settings of "standard substitutions",
  126.     such as "today's date".
  127.  
  128.     The option, -r, causes a list of number registers to
  129.     be typed to the console.  Could be useful to find
  130.     the number of footnotes, etc.
  131.  
  132.     The option, -g, causes a glossary of defined
  133.     translated characters to be printed on the output
  134.     device.  It is useful to check the appearance of
  135.     all special definable characters and to produce
  136.     a "wall chart" of special characters available.
  137.  
  138.     The default option, -*, (the * could be any
  139.     unassigned option) means keyboard input (buffered
  140.     line-by-line with a prompt with the character used in
  141.     the option, here *).  Typing a control-Z indicates
  142.     an end-of-file; the formatter will continue with the
  143.     next named file.  It is intended as a learning aid
  144.     since one can tryout "tricky" input such as
  145.     equations.  As with standard CP/M and MS-DOS, a 
  146.     control-P can be used to toggle the printer to
  147.     display output that would normally be sent to the
  148.     console; also, one can edit the keyboard input with
  149.     the backspace key.
  150.  
  151.     Using ROFF5, you can make nice printouts of a file,
  152. with as little or as much help from the program as you want,
  153. depending on the commands.  There are default values for all
  154. parameters, so if you don't put any commands in at all, your
  155. file will come out with filled, right-justified lines.  The
  156. default line-length is 66 characters and we have defaulted the
  157. conventional tab stops to every fifth column; the default page-
  158. length is 66 lines per page.  "Filled lines" means that as
  159. many input words as possible are packed onto a line before
  160. it is printed; "non-filled" lines go through the formatter
  161. w/o rearrangement.  "Right-justified" simply means that
  162. spaces are added between words to make all the right margins
  163. line up nicely.  To set a parameter, use the appropriate
  164. commands below. All commands have the form of a period
  165. followed by one or two characters;  any non-blank contiguous
  166. non-blank characters following a recognized command will be
  167. passed over by the formatter.  Thus, ".else" could be used
  168. instead of ".el".   A command line should have
  169. nothing on it but the command and its arguments (if any);
  170. any text would be lost. 
  171.  
  172.     Extra space will separate text sentences.  The sentence
  173. is recognized by a trailing ':',';','!','?', or a '.'.  For
  174. the '.' there is the additional requirement that either two
  175. or more spaces must follow it, or that it is at the end of
  176. the source line.
  177.  
  178.         A command argument can be either ABSOLUTE or RELATIVE : 
  179.  
  180. .ls    5    sets the line spacing to 5 
  181.  
  182. .ls    +5    sets the line spacing to the CURRENT value+5
  183.  
  184. .ls     -1    sets the line spacing to the CURRENT value-1
  185.  
  186.  
  187.     Also,  all commands have a minimum and maximum value
  188. that will weed out any odd command settings (like setting
  189. the line spacing to zero, for example. It won't let you do
  190. that, but it could be changed if you REALLY have a burning
  191. desire to do so).
  192.  
  193.     Some commands cause a "break", which is noted in the
  194. table below.  Before such a command goes into effect, the
  195. current line of text is put out, whether it is completely
  196. filled or not. (this is what happens at the end of a
  197. paragraph, for example.)  A line beginning with spaces or a
  198. tab will cause a break, and will be indented by that many
  199. spaces (or tabs) regardless of the indent value at that time
  200. (this is a "temporary indent", which can also be set
  201. explicitly).  An all blank line also causes a break.
  202.  
  203. We part company with ROFF4, nroff, and troff by not having as
  204. many commands produce a break;  we reasoned that one can more
  205. easily add the .br where needed (and still be compatible with these
  206. other formatters).  If you find that some lines that are indented
  207. strangely, and it's not obvious WHY, look at which commands are
  208. causing a break, and which aren't.
  209.  
  210.  
  211.     Certain system variables are "stacked" to enable
  212. reversion to earlier environments instead of "hardcoded"
  213. defaults.  For example:
  214.  
  215. .ls 1
  216.  .
  217.  .
  218.  .
  219. .ls
  220.  
  221. The first command will produce single line spacing (which is
  222. the default, but which may have been set otherwise at the
  223. beginning of the manuscript).  The second command causes
  224. resumption of the original line spacing (either the default
  225. or whatever had been chosen previously).  Stacked variables
  226. include: linespacing, indent column, right margin,
  227. translation flag character, page length, top and bottom
  228. margin sizes, unexpandable space character, insert character,
  229. environment, and control flag character.
  230.  
  231. *********************** Table of Commands *********************
  232.  
  233. Command          Break?    Default    stacked    Function
  234. -------       ------    ------- ------- ---------
  235. .. string    no            string is "mere"comment
  236.  
  237. .;;        no            end the macro definition
  238.  
  239. .{        no            start a group of lines subjected
  240.                     to conditional, such as ".if"
  241.  
  242. .}        no            end group started by ".}"
  243.  
  244. .ab string    no    USER ABORT    immediate abort back to
  245.                     system
  246.  
  247. .ad c        both    both    No    adjust margins; c=b(oth),
  248.                      l(eft), r(ight), c(enter)
  249.                     [if "filling" also]
  250.  
  251. .af name picfmt            no    assign format to number reg.
  252.                     (see "PREPROCESSOR")
  253.  
  254. .am name                append to macro or create.
  255.  
  256. .bj        yes            break with right
  257.                     justification (current
  258.                     line only)
  259.  
  260. .bp n        yes    n =  +1        begin page numbered n
  261.  
  262. .br        yes            cause a break (this
  263.                     line is not justified)
  264.  
  265. .ce n        yes    n = 1        center next n lines
  266.  
  267. .cf c        no    c = '^'    Yes    to be used as a prefix
  268.                     to a character that
  269.                     controls print func-
  270.                     tions such as ^+,^-
  271.                     might be used to
  272.                     bracket    superscripts,
  273.                     somewhat like
  274.                     WORDSTAR(TM).
  275.  
  276. .ch macro n    no            relocates a .wh request.
  277.  
  278. .cz n        no            control-Z substitution out.
  279.  
  280. .da name    no    (end diversion) append or create a diversion
  281.  
  282. .de name    no            define (multiline)
  283.                     macro ("PREPROCESSOR")
  284.  
  285. .di name    no    (end diversion) start diversion named name
  286.                     (see "PREPROCESSOR")
  287.  
  288. .ds name string    no    string="" no    define string replace-
  289.                     ment ("PREPROCESSOR")
  290.  
  291. .ef /../../../    no    blanks        even footer titling
  292.  
  293. .eh /../../../    no    blanks        even header titling
  294.  
  295. .em name        (removes)    End Macro;  acts if .name
  296.                     was placed at end of last
  297.                     file read in.
  298.  
  299. .el anything    no            "Else" part of .ie ...
  300.  
  301. .ev n        no    0    yes    switch environments
  302.  
  303. .fi        yes            start filling lines
  304.  
  305. .ff n        no    n = 1(yes)    initially, formfeeds
  306.                     are "off". Can turn
  307.                     them on.  Each page
  308.                     then terminated with
  309.                     one formfeed.
  310.  
  311. .fo /../../../    no    empty        sets both even and odd
  312.                     page footers
  313.  
  314. .fr # base - ;    no    1,no action    defines how to put
  315. - - - -    .                output device in mode
  316.                     for fractional and whole
  317.                     line spacing (for super-,
  318.                     sub- scripting); see 
  319.                     "PRINTER CONTROL",
  320.                     given below.
  321.  
  322. .go n                    go (advance) to line n.
  323.  
  324. .he /../../../    no    empty        sets both even and odd
  325.                     page headers
  326.  
  327. .ic c        no    c = '\'    Yes?    to specify the interpolation
  328.                     character used for macro
  329.                     string and register
  330.                     preprocessing.
  331.  
  332. .ie expr anything no    expr=FALSE    begin If-Else cond. macro.
  333.  
  334. .if expr anything no    expr=FALSE    If expr non zero, then anything.
  335.  
  336. .ig string    no            "ignore" following lines until
  337.                     .string line is found
  338.  
  339. .it n macro    no    removes n    sets input trap.
  340.  
  341. .lc c        no    blank   No    Leader expansion Character;
  342.                     initially '.'.
  343.  
  344. .ls n        no    n = 1    Yes    set line spacing to n
  345.  
  346. .m1 n        no    n = 2    Yes    set topmost margin to n
  347.  
  348. .m2 n        no    n = 2    Yes    set 2nd top margin to n
  349.                     lines
  350.  
  351. .m3 n        no     n = 2    Yes    1st bottom margin to n
  352.                     lines
  353.  
  354. .m4 n        no    n = 2    Yes    bottom-most margin to n
  355.                     lines
  356.  
  357. .mc                    [not yet implemented]
  358.  
  359. .ne n        no/yes    n = 2    /yes    "need" n lines; if have
  360.                     them no action; else
  361.                     begins new page
  362.  
  363. .na        no    initially    turn off justification
  364.             is justifying    [only relevent
  365.                     if "filling" also]
  366.  
  367. .nf        yes            stop filling lines
  368.  
  369. .nm N M S I            No    line Number Mode.
  370.  
  371. .nn n            n=1    No    No line Numbering.
  372.  
  373. .nr name n    no    n=0    No    create or modify number
  374.                     register variable
  375.                     (see "PREPROCESSOR")
  376.  
  377. .of /../../../    no    empty        odd page footer title
  378.  
  379. .oh /../../../    no    empty        odd page header title
  380.  
  381. .ot ~c|^c base - ; no    not applicable    used to create
  382. - - - .                    definitions for special
  383.                     character fonts/printer
  384.                     control.
  385.  
  386. .ou base - - ;    no    not applicable    direct output of code
  387. - - - .                    sequences to output.
  388.  
  389. .pc                    [not yet implemented]
  390.  
  391. .pl n        no     n = 66    Yes    sets page length to n
  392.  
  393. .pm        no            print macros to stderr.
  394.  
  395. .po n        n=0    n=0    No    page offset.
  396.  
  397. .rl ?/string    no    ignore        shows/sets line and tab format.
  398.                                         (see RULER...)
  399.  
  400. .rm names1 ? names2            removes definitions named names1
  401.                     and named names2; error message
  402.                     for not finding names2 only.
  403.  
  404. .rn old new    no    (error)        rename definition; names
  405.                     must be same length.
  406.  
  407. .sc c        no    blank    Yes    space character; the
  408.                     visible character
  409.                     that will be trans-
  410.                     literated to unexpanded
  411.                     blank.
  412.  
  413. .so filename    no    ignored    Yes    reads named file into
  414.                     input stream; cannot be
  415.                     invoked from keyboard
  416.                     input.
  417.  
  418. .sp n        yes    n = 1        space down n lines
  419.  
  420. .st n        no    n=1(yes)    stop(pause)at each page
  421.                     start; initially off;
  422.                     may also be enabled by
  423.                     the -s option.
  424.  
  425. .tc c        no    blank    No    tab expansion or fill
  426.                     character.
  427.  
  428. .tf c        no    '~'    Yes    Translation flag character.
  429.  
  430. .tl 'string1'string2'string3'        generates 3 part title.
  431.  
  432. .tm string                terminal message;
  433.                     like a comment
  434.                     but displayed to
  435.                     operator during run.
  436.  
  437. .ti [+-]n    yes    n = 0        set temp. indent of n
  438.                     optional sign is relative
  439.                     to normal left margin.
  440.  
  441. .wh n macro    no    no action    "when" trap springs macro at
  442.                     line n on output pages.
  443.  
  444. -------------------------------------------------------------
  445.  
  446.  
  447.  
  448. Here's what the page parameters look like:
  449.  
  450. (.po)-->|
  451. _    _________________________________________________
  452. |    |    top margin(m1) - (includes header)    |
  453. |    |-----------------------------------------------|
  454. |    |        top margin 2            |
  455. |    |-----------------------------------------------|
  456. P    |    :                :    |
  457. A    |    :<-indent            :    |
  458. G    |    :                :    |
  459. E    |    :lots and lots of silly text and:    |
  460. L    |    :other garbage. Get the picture?:    |
  461. E    |       :This is a temp.  indentation:    |
  462. N    |    :                :    |
  463. G    |    :        right margin -> :    |
  464. T    |    :                :    |
  465. H    |    :                :    |
  466. |    |-----------------------------------------------|
  467. |    |        margin 3            |
  468. |    |-----------------------------------------------|
  469. |    |  margin 4 - (includes footer,perhaps ff)    |
  470. -    -------------------------------------------------
  471.  
  472. Minimum acceptable values for M1, M2, M3, and M4; if M1 is set
  473. to zero, no header will be shown (even if one was declared).
  474. Similarly, if M4 is set to zero, no footer will be displayed.
  475.  
  476.  
  477. To change the default for any parameter, simply alter ROFF5.H
  478. and recompile and link.
  479.  
  480. ------------------------------------------------------------
  481.  
  482.     The numerical argument, n, and the expression, expr, of the
  483. conditional commands (.if and .ie) can be calculated or evaluated by
  484. ROFF5.  For example, ".sp 3+4" is equivalent to ".sp 7".  A leading
  485. "+" or "-" sign is still used to indicate "relative" values.  For
  486. example, ".ti -1+1" is equivalent to ".ti -2".  There should not be
  487. any white space within the expression.  A leading "!" can be used to
  488. convert a "true" expression to "false", and vice versa.
  489.  
  490.     Calculations use the usual precedence rules where
  491. parenthesized portions are evaluated first, multiplication and
  492. division are evaluated left to right, addition and subtractions are
  493. then evaluated (also left to right) and, lastly, the logical and
  494. comparison operations are performed left to right.  The logical
  495. "and" and "or" are represented by the symbols "&" and ":",
  496. respectively.  A subexpression is "true" if non-zero and "false" if
  497. zero.  The comparison operations are: "<", "<=", "=", ">=, and ">".
  498.  
  499.     One can use number registers in expressions by using "\"s in
  500. sufficient quantities to bracket them [see the section on the
  501. "PREPROCESSOR", below].  For register names which are beginning with
  502. a letter and consist of only letters and numbers (such as "date",
  503. "x1", "name23", etc.) the evaluation will convert them automatically
  504. (they must already be defined!).
  505.  
  506. ***********************************************************
  507. A Few Extra Comments on Some of the Commands:
  508. ************************************************************
  509.  
  510.                 If you want to center lots of lines, but don't
  511.         want to count them, do something like this:
  512.  
  513. .ce    1000
  514. lots and
  515. lots of words to
  516. be centered
  517. .ce 0
  518.  
  519.         --------------------------------------
  520.  
  521. A new paragraph may be caused by using the temporary indent
  522. command, like
  523.  
  524. .ti +5
  525.  
  526. or by simply beginning the paragraph with a tab, as you would
  527. if you were just typing.  If there is an indented left margin by a
  528. ruler command of the general form:
  529.  
  530. .rl "    L---...etc. R" ,
  531.  
  532. one can have "hanging" temporary indents by using a negative value
  533. for the numerical argument.
  534.  
  535.         ------------------------------------
  536.  
  537.     For special cases, where you wish to place the last
  538. "word" at the right-hand margin, such as numbers of equation,
  539. for example:
  540.  
  541.             x = y+z                (12)
  542. you could input:
  543.  
  544. # x#=#y+z (12)
  545. .bj
  546.  
  547. because we force a break with justification (.bj) of the
  548. line with only "three words". (The # is assumed to be the
  549. "space character" set up with a .sc command).
  550.  
  551.     Other ways we could achieve similar results for equations
  552. would be to use the .tl (title) command:
  553.  
  554. .tl //x = y+z/(12)/
  555.  
  556. or to set up a special environment and use tabs.
  557.  
  558.         ------------------------------------
  559.  
  560. Headers, Footers, and Titles.
  561.  
  562.         A page number can be incorporated into any header, footer,
  563. or title by putting a "#" into the command line where you want the number
  564. to go:
  565.  
  566. .he    /This is a witty header title for page #/
  567.  
  568. Each time this is printed at the top of a page, the current
  569. page number will be substituted for the "#".
  570.  
  571. Headers, footers, and titles are in three parts.  These parts are left
  572. justified, centered, and right justifed.  Any of these three
  573. parts may be left out.  The right justification is fixed to the
  574. margin that is set by the .OW command.  One may pick the
  575. headers and footers separately for even and odd pages.  For
  576. example, one could place even and odd page numbers at the
  577. bottom outside of each page by:
  578.  
  579. .ef /Page #///
  580. .of ///Page #/
  581.  
  582.     Any printable character, here the '/', can be used to
  583. delimit the three strings that make up the titles, so long
  584. as it is not the "insert character" (usually, '\') and is
  585. not present in any of the three strings.
  586.  
  587.     Headers and footers obey margins established for environment
  588. 1;  titles (created from the .tl command) are processed in the
  589. current environment.  They all are not considered text lines;  they
  590. are not counted by the line numbering provided by the .nm command.
  591.  
  592.     ------------------------------------
  593.  
  594.     The program can be made to wait for the operator to
  595. load single sheets of paper by the -s option and/or by the
  596. command: .st
  597.  
  598.         ------------------------------------
  599.  
  600. If you want to send the output to a file, and don't want the
  601. page breaks in there set margins 1-4 to zero.
  602.  
  603.     ------------------------------------
  604.  
  605.     Where you need to supply code sequences for
  606. immediate or for subsequent output (for .ou or for .ot) one
  607. needs to supply the number base (binary, octal, decimal, or
  608. hexadecimal) by supplying a token that begins with (upper
  609. and lowercase are both o.k.): b, o(or q), d, or h. Following
  610. the base on the same and/or subsequent lines one supplies
  611. the codes that will form the "code string". These codes are
  612. delimited by white space (not commas!) and the sequence is
  613. eventually terminated by a token beginning with a period.
  614. The ends of any of these lines may contain comments if they
  615. are set off by white space and a semicolon. For examples:
  616.  
  617. .ou hex 11 1C 8C 0
  618. 99 6C 55 ;get ready!
  619. .end
  620.  
  621. .ot ~= binary ;"identity"operator (triple equal sign) on MX-80
  622. 00011011 ;ESC
  623. 01001011 ;4B
  624. 00000110 ;6 bit patterns
  625. 0     ;follow:
  626. 00101010 ;left top,bot
  627. 00101010
  628. 00101010
  629. 00101010
  630. 00101010
  631. 00000000 ;right top,bot
  632. .end
  633.  
  634.     The first of these examples might be used to get
  635. some strange printer to cooperate in standing on its head or
  636. something.  
  637.  
  638.     The second, lengthier example is taken from a file,
  639. MX, that defined quite a number of special characters for
  640. the MX-80 with GRAFTRAX 80.  Because that printer uses dot
  641. graphics, I chose to make the definition in binary so that
  642. the placement of the individual dots is easier to visualize.
  643. Later, in the text the combination: ~=  will cause the
  644. printer to be sent this code so that it will print the
  645. specialized symbol.
  646.  
  647.               SPECIAL SYMBOLS
  648.  
  649.     If one includes a set of definitions such as in the
  650. MX file, one can specify the use of special symbols, which
  651. can be chosen to fit the application (and the hardware!) For
  652. example, the MX-80 printer equipped with GRAFTRAX 80 can
  653. accept dot addressed graphics.  [See the MX file for
  654. examples with this hardware].  Other printers may be able to
  655. simulate symbols by a combination of overstruck characters.
  656. Still other output devices may be capable of displaying
  657. desired special symbols by use of the "parity bit".
  658.  
  659.     The .ot and .tf commands define the codes for the
  660. special symbols and the translation flag character.  To create a
  661. "wall chart" that lists the special characters on the output
  662. device you could use the -g option on the command line, for
  663. example:
  664.  
  665. A>roff5 mx80 -g )
  666.  
  667.  
  668.         ====================================
  669.  
  670.  
  671.               PRINTER CONTROL
  672.  
  673.     It is assumed that the output device can accept
  674. carriage returns and will not linefeed in the absence of the
  675. linefeed character.  Using this assumption, super- and
  676. subscripting, backspacing, underscoring, strickout, and
  677. multiple impressions are supported in a manner somewhat
  678. analogous to WORDSTAR [tm by MicroPro], but more generally.
  679.  
  680.     If the printer can be placed in fractional
  681. linespacing mode, so much the better, as full line spacing
  682. for super- and subscripts does not look as "natural".  Also,
  683. with the half line spacing, one can build up larger
  684. characters (such as summation and integration symbols) since
  685. some overlap does occur.  To implement such fractional
  686. spacing one uses the command: .fr (probably at the
  687. beginning of the input file, along with other information
  688. relevent to the output device and style).  These commands
  689. describe the operational codes sent to the output to switch
  690. the printer to FRactional spacing and back to whole line
  691. spacing.
  692.  
  693.     For example,  I use for the MX-80 printer equipped
  694. with GRAFTRAX 80 the following:
  695.  
  696. .fr 1 HEX 1B 32 . ;(whole line) 6 lines/inch is standard
  697. .fr 2 hex 1b 33 12 . ; 18/216" = halfline spacing
  698.  
  699. The initial 2 in the second .fr tells the formattter that 2
  700. fractional [half] lines are equivalent to a conventional whole
  701. line.  The original description of the required codes were in
  702. hexadecimal, so I kept matters as simple as possible by
  703. using the same number base so that I would not make any
  704. conversion mistakes!
  705.  
  706.     The printer control requests are embedded in the
  707. text; they are NOT set off in separate lines as the "dot"
  708. commands are set apart.  Each request is made up of two
  709. printable characters, the first of which is the "control
  710. flag character" (the default is '^').  Here is a table of
  711. control functions presently supported by ROFF5,
  712. version 2.00:
  713.  
  714. ^+    up a fractional line; may be used several times to
  715.     increase vertical rise. [used at start of a
  716.     superscript and at the end of a subscript]
  717.  
  718. ^-    down a fractional line; may be used several times to
  719.     increase vertical drop. [used at the start of a
  720.     subscript and at the end of a superscript]
  721.  
  722. ^h,^H    backspace one character column.  Do NOT backspace
  723.     over ordinary blanks ("unexpandable" space is o.k.)
  724.     if you are in "fill" mode.
  725.  
  726. ^(,^)    Note current column position; return to noted position.
  727. ^[,^]    "    "    "    "    "    "    "
  728. ^{,^}    "    "    "    "    "    "    "
  729.  
  730.     The above three pairs of controls are often more
  731.     convenient then multiple, explicit backspaces, ^H,
  732.     especially for "built-up" fractions and matrices.
  733.  
  734. ^A,^a    Leader character, similar to a tab, but typically used with
  735.     a leader repetition character, such as '.', to form table
  736.     of contents entries.
  737.  
  738. ^B,^b    Start, end boldface (increase, decrease the number
  739.     of impressions by a factor of 3).
  740.  
  741. ^D,^d    Start, end doublestrike (increase, decrease the number
  742.     of impressions by a factor of 2).
  743.  
  744. ^T,^t    Tabs typically used for paragraphs and for coulumnar
  745.     information;  although usually used only for motion, it can
  746.     mimic the leader character by defining some tab expansion
  747.     character with the .tc command.
  748.  
  749. ^U,^u    Start, end underscore (will not underscore
  750.     expandable white space; will ride up and down with
  751.     super and subscripts.)
  752.  
  753. ^X,^x    Start, end strikeout (similar to underscore, above,
  754.     but overprints with '-' instead of underlines).
  755.  
  756.  
  757.     Note that the B, D, U, and X pairs are "case sensitive";
  758. namely, the uppercase starts some activity, whereas the
  759. lowercase equivalent sqelches it;  these controls are
  760. NOT "toggles".
  761.  
  762.     An involved example of the use of printer controls
  763. would be to create a 3 by 3 matrix:
  764.  
  765. MATRIX =#^+^+^(|1#2#3|^)^-^-|4#5#6|^)^-^-|7#8#9|^+^+
  766.  
  767. which should produce (with a half-spacing) printer:
  768.  
  769.  
  770.          |1 2 3|
  771. MATRIX = |4 5 6|
  772.          |7 8 9|
  773.  
  774. [the demonstration file, MATRIX, has been provided as a
  775. demonstration of the above].
  776.  
  777. Several points should be observed.  There should be no
  778. expandable blank spaces if you are in fill mode, otherwise,
  779. the result might be very strange! (ROFF5 does some checks to
  780. flag such attempts). We are assuming here that the '#' are
  781. unexpandable spaces (chosen with the .sc command).  The
  782. first printable character in the complex, the '=', is at the
  783. leftmost edge; the last printable character, the '|'
  784. following the '9', is at the rightmost edge of this
  785. assemblage.  The final height is adjusted (by the trailing
  786. ^+^+ ) to match the initial height.  The present limit of
  787. the line buffering is 255 characters; I assume that is not
  788. too chancy.
  789.  
  790.     One can define additional printer control codes
  791. using the .ot command.  For example, the MX-80 printer with
  792. Graftrax is switched to italics with the sequence <ESC> '4';
  793. and italics are turned off with <ESC> '5'.  We could define
  794. ^I to start italics and ^i to end them:
  795.  
  796. .ot ^I hex ;italics on (MX-80 & Graftrax)
  797. 1B 34
  798. .en
  799. .ot ^i hex ; italics off (MX-80 & Graftrax)
  800. 1B 35
  801. .en
  802.  
  803.           ================================
  804.                     RULER LINE AND TABS
  805.                     ===== ==== === ====
  806.     We liked the idea introduced by WordStar(TM by MicroPro) of
  807. the "ruler line" which is a picture description of the location for
  808. margins, and tab stops.  It can facilitate the composition of
  809. tabular information.  Our implementation is neither close to that of
  810. WordStar nor to Unix(R by AT&T)'s nroff or troff.  We hope that we
  811. have achieved the best of the two, in terms of convenience, clarity,
  812. and of flexibility.
  813.  
  814.     Each environment has its own ruler;  its ruler can be
  815. set or changed or observed at anytime by use of the .rl command.  We
  816. include here a brief example to illustrate how it is used:
  817.  
  818. .nf
  819. .rl "     L---------l---------c----------r---.-----,-----R"
  820. .rl ?
  821. x^Txxxxx^txxxxx^Txxxxx^Tx.xx^txx,x
  822. .fi
  823. Now is the time for all good persons to come to the aid of their
  824. country... x^Txxxxx^txxxxx^Txxxxx
  825. x^Txxxxx^txxxxx^Txxxxx^Tx.xx^txx,x
  826.  
  827. The first line declares that we are to be in "no fill" mode so that
  828. we can see the effects of the tab settings; this mode is most
  829. appropriate to presenting tabular information.  The second line sets
  830. or changes the "ruler line".  The "L" and "R" are locating the left
  831. and right margins of future output.  In order to "see" the 5 leading
  832. blanks (so that we can indent 5 spaces) we have enclosed the string
  833. argument in double quotes.  The third line uses the same command,
  834. but with the argument, "?" which will cause the ruler line to be
  835. displayed in the output.
  836.  
  837.     To explain the remaining actions we shall show the output
  838. that would be produced:
  839.  
  840.      L---------l---------c----------r---.-----,-----R
  841.      x         xxxxx   xxxxx    xxxxx  x.xx xx,x
  842.      Now  is the time for all good persons to come to
  843.      the aid of their country... x xxxxx xxxxx  xxxxx
  844.      x xxxxx xxxxx xxxxx x.xx xx,x
  845.  
  846. In keeping with our design philosophy that the input stream should
  847. be printable on any generic ASCII device (and be visually scanned
  848. unambiguously), we did not want to require that actual tabs (ascii
  849. 8) be used.  We can use the character pairs, "^t" or "^T", instead.
  850. The forth input line contains short words of x's separated by the
  851. character pairs representing tabs.
  852.  
  853.     We see in the first two output lines, shown above, that we
  854. have the current ruler line and how it causes the tabs to be
  855. processed.  The "l" in the ruler line indicates a (conventional)
  856. "left" tab stop.  Such a tab stop causes the output to be advanced
  857. horionatlly so that the next character begins with that position; 
  858. it provides alignment of the left edge.  The "c" in the ruler line
  859. indicates a "centering" tab position;  we see that the next tabbed
  860. group of x's are centered under it.  Similarly, the "r" indicates a
  861. right tab stop for alignment of right edges.  We have provided two
  862. other tab position types indicated by "." and ",";  they provide
  863. alignment for decimal point data, such as financial information, for
  864. both American and European usages.
  865.  
  866.     When the input reverts to "fill" mode by the use of the .fi
  867. command, the tab positions loose much of their significance (except
  868. for leading tabs, say, for the start of a paragraph).  However, the
  869. right and left margins are most important for controlling the fill
  870. mode's line sizes.  The tabs that are used to separate words now are
  871. treated as equivalent to spaces in the input stream.
  872.  
  873.           ================================
  874.                          OFFSETS
  875.                          =======
  876.  
  877.     We shall describe the different ways that the lines of
  878. output are offset from the left-hand margin.  The page offset is
  879. controlled by the .po command.  It is usually set once, and only
  880. before any output has been generated.  It is intendended to locate
  881. the page relative to the output device's left-hand physical edge.
  882.  
  883.     The printed lines are usually controlled by the .rl command,
  884. as was described above.  In order to simplify indenting or having a
  885. hanging indent at the start of a paragraph, we have the .ti
  886. (temporary indent) command that can affect only the next line that
  887. is being placed on the page.  It can be absolute (relative to the
  888. page offset, anyway), or by using an argument preceeded by a "+" or
  889. "-" can be relative to the current indent (determined by .rl).
  890.  
  891.     When one uses automatic line numbers in the margin by means
  892. of the .nm command, the text margin is indented additionally to make
  893. space for the numbers that will occupy the margin.  The 4 parameters
  894. for this command are somewhat complex, but we have followed (I
  895. think) the nroff/troff conventions here.  Not all the parameters
  896. need to be supplied.  The full command, .nm N M S I, provides the
  897. following options:  N specifies the number used at the start of
  898. line counting;  M specifies the multiple number of lines between
  899. display of the count (M=5 would display 5,10,15,etc.);  S provides
  900. the choice of spacing between the end of the number and the
  901. beginning of text (default is 1);  "I" specifies an indent between
  902. the line numbers and the left margin.
  903.  
  904.     It should be noted that the numbering is for lines of text,
  905. not for blank lines nor for titles, either produced by the .tl
  906. command or by header and footer commands.  Also, note that the "no
  907. numbering" request (.nn) does not negate all of the effects of .nm; 
  908. to completely finish numbering, one should use ".nm" (no
  909. arguments).
  910.  
  911.           ================================
  912.               THE PREPROCESSOR
  913.               === ============
  914.  
  915.     In the following we describe the advanced macro
  916. preprocessing features of this formatter which provide users
  917. with labor saving tools but which are probably not necessary
  918. at first.  The beginning user may be able to achieve most
  919. goals without the "preprocessing", but by using an editor
  920. more then otherwise.  The more advanced user will begin to
  921. appreciate these features more.
  922.  
  923.     In the following discussion we will assume the
  924. default insert character, '\', and the default command
  925. character, '.', will be used.  (It is rare that you should
  926. change these anyway!)
  927.  
  928.     The insert character is used to denote where a
  929. replacement should be used.  For example, in:
  930.  
  931. Today, \date\, is special.
  932.  
  933. the block, "\date\", would be replaced as this sentence is
  934. being input.  If a prior string definition of the form:
  935.  
  936. .ds date "January 1, 1983"
  937.  
  938. had been processed previously then the example, after text
  939. substitution, would become:
  940.  
  941. Today, January 1, 1983, is special.
  942.  
  943. If no string definition had been provided for "date", the
  944. user will be prompted while the formatter is trying to input
  945. this sample line.  The console will get some message like:
  946.  
  947. [Bell]Please define <date>:
  948.  
  949. Whatever you type in will be used to form an "effective" .ds
  950. definition.  This feature should be useful in applications
  951. where information should be changed or updated each time the
  952. formatter is run, such as today's date, the addressee's name
  953. and address in a form letter, etc.  A sample file, FORM is
  954. included to demonstrate both of the above means to define
  955. string substitutions.
  956.  
  957. An important restriction must be observed when using
  958. "definitions on the run".  They must not be first used
  959. inside of multiline definitions (namely inside of .ou, .ot, .de,
  960. and .fr) because the building of both definitions will cause them to
  961. interfere with each other.  ROFF5, v2.00 will test for such
  962. contention and abort operation if one is found.  An example of such
  963. a situation and its remedy is shown below:
  964.  
  965. .tm chose 0 for DRAFT and 1 for CORRESPONDENCE
  966. .ou hex
  967. 1B
  968. 3\font\
  969. .end .ou
  970.  
  971. This example, which might be used to initialize the Okidata
  972. Microline 92 printer to go into correspondence quality or
  973. into draft quality printing would cause problems if "font"
  974. is supposed to be defined here during execution.  We are in
  975. the midst of defining an output string for the printer (ESC
  976. "0" or ESC "1") when we are asking ROFF5 to create
  977. (simultaneously) a definition for "font";  the program will
  978. abort rather than continue with the two definitions mangling
  979. each other.  Here is a modified version of above without the
  980. problem:
  981.  
  982. .tm chose 0 for DRAFT and 1 for CORRESPONDENCE
  983. .. this comment containing \font\ is "ignored"
  984. .ou hex
  985. 1B
  986. 3\font\
  987. .end .ou
  988.  
  989. The fix here is that the formatter will encounter "\font\"
  990. in the comment and complete a definition for "font" before
  991. tackling the .ou command;  no simultaneous definitions, no
  992. problems!
  993.  
  994.     Similar to string definitions are register
  995. variables, which are created and modified with the .nr
  996. command.  Variables are useful for enumeration such as
  997. equation numbering:
  998.  
  999. .nr eqnum 1
  1000.  
  1001. would create a register named "eqnum" with the current value
  1002. of 1.  The the text might use it with, say:
  1003.  
  1004.          x = y+1          (\eqnum\)
  1005.  
  1006. which would be converted on input into:
  1007.  
  1008.          x = y+1          (1)
  1009.  
  1010. A subsequent instruction:
  1011.  
  1012. .nr eqnum +1
  1013.  
  1014. would take the current value of "eqnum" and increase it by 1
  1015. (so that it would now be 2 in our example:
  1016.  
  1017.          a = b+c          (\eqnum\)
  1018.  
  1019. would become:
  1020.  
  1021.          a = b+c          (2)
  1022.  
  1023.     There is a special, reserved insertion, \#\, which
  1024. will provide the current page number.  It should prove
  1025. useful in setting up tables of contents (see "diversions",
  1026. below).  Trivial examples of its use are to be found in the
  1027. files, BPTEST and MARGINS.  In rare cases it may be off one
  1028. page because it may be read while between pages;  how can one
  1029. handle the sentence, "This sentence is on page XXX," when the
  1030. sentence straddles two pages?
  1031.  
  1032.     Since we have defined a special register name, '#',
  1033. we should comment on what happens if you create a register
  1034. instruction with that name, such as:
  1035.  
  1036. .rg # +1
  1037.  
  1038. You will be changing the value of the page number of the
  1039. FOLLOWING pages.  This is useful for leaving gaps in the 
  1040. pagination for later inclusion of full page illustrations.
  1041. This feature is demonstrated (tested) in the file, MARGINS.
  1042. I wish to thank Henry Harpending for suggesting this.
  1043.  
  1044.         We can choose a variety of output formats for number
  1045. register display.  If a register named "R", say contains the value,
  1046. 3, we can have "\R\" be replaced by "3", by "   3", by
  1047. "....3","iii", "  iii", "  III", "c", "C", "   C",
  1048. etc. by assinging a format to this register with the command:
  1049.  
  1050. .af R picfmt
  1051.  
  1052. where the form of picfmt indicates the minimum width of the field,
  1053. the representation of the numbe and the fill character used on the
  1054. left of the field if the representation of the number would
  1055. otherwise be less than the minimum field width.  The picfmt may be
  1056. enclosed in quotation marks;  this is important if it contains
  1057. blanks.  The width of picfmt determines the minmum width of the
  1058. output representation, the leftmost character of it provides the
  1059. fill character to be used if necessary to pad the representation on
  1060. the left up to the minmum filed width.  The rightmost character of
  1061. the picfmt choose the format:
  1062.  
  1063. char  numbering
  1064. ====  =========
  1065. 1     0,1,2,3,4, etc.
  1066. i     0,i,ii,iii,iv, etc.
  1067. I     0,I,II,III,IV, etc.
  1068. a     0,a,b,c,..,aa,ab,..,aaa,aab,...
  1069. A     0,A,B,C,..,AA,AB,..,AAA,AAB,...
  1070.  
  1071. So, for example, to obtain 000,001,..010,011,..999 we could use the
  1072. picfmt of 001.  Similarly, in a table of contents to
  1073. get ....i, ...ii, etc., we could use a picfmt of "....i".
  1074. The format of page numbering can also be controlled by:
  1075.  
  1076. .af # picfmt
  1077.  
  1078.     There are a number of registers that are "read only" and
  1079. predefined.  They are accessed as any other register would be, but
  1080. they canNOT be altered by the ".nr" command (nor by ".af"):
  1081.  
  1082. .F    current filename
  1083. .L    Line spacing value
  1084. .c    number of lines read from input
  1085. .d (?)    current number of lines in text or diversion output
  1086. .i    current indent
  1087. .j    current adjustement mode
  1088. .l    current line length
  1089. .m1    current vertical margin (for command .m1)
  1090. .m2    current vertical margin (for command .m2)
  1091. .m3    current vertical margin (for command .m3)
  1092. .m4    current vertical margin (for command .m4)
  1093. .o    current page offset
  1094. .p    current page length
  1095. .u    fill mode?
  1096. .x    version number (currently 2)
  1097. .y    subversion number (currently 0)
  1098. .z    current diversion name
  1099. dl    width of last completed diversion
  1100. dn    vertical size of last completed diversion
  1101. ln    current line number (.nm command)
  1102.  
  1103. The choice of names is strongly influenced by nroff/troff;  They are
  1104. not necessarily "read only" for these other formatters.
  1105.  
  1106.  
  1107.     The insert character has other properties.  The
  1108. insert character can be placed into the input by repeating
  1109. it, namely, "\\" becomes "\".  (useful for delaying
  1110. substitutions).  For example, defining:
  1111.  
  1112. .ds EN (\\eqnum\\)
  1113.  
  1114. will identify "EN" with "(\eqnum\)" and so our equation
  1115. example above could have been:
  1116.  
  1117.          a = b+c          \EN\
  1118.  
  1119. Delaying the evaluation of "eqnum" until EN is invoked
  1120. (instead of when it was defined) means that the proper
  1121. numbering of equations will occur instead of wrongly
  1122. supplying the value of "eqnum" from the time that EN was
  1123. first created.
  1124.  
  1125.     If the insert character is at the end of a line, it
  1126. negates the following newline sequence;  thus the next line
  1127. is merged with the current line.  For example:
  1128.  
  1129. antidisestab\
  1130. lishmentarianism
  1131.  
  1132. is equivalent to:
  1133.  
  1134. antidisestablishmentarianism
  1135.  
  1136.     Yet another use of the insert character, '\', is to form a
  1137. commnet at the end of a line, in the style of nroff and troff.
  1138. Any input line that has a \" will have that and what follows in that
  1139. same line ignored by the preprocessing in the formatter.
  1140.  
  1141.     "Macro" definitions are used when we wish to
  1142. identify several lines with an insertion.  Such definitions
  1143. are created with the .de ["DEfine macro"] and completed with
  1144. the .;; ["end macro"] commands.  For example, we might wish
  1145. to use the following sequence over and over again at the
  1146. start of paragraphs:
  1147.  
  1148. .sp 1
  1149. .ne 2
  1150. .ti +5
  1151.  
  1152. to separate the paragraphs by blank lines, keep them from
  1153. starting excessively close to the bottom of the page, and
  1154. indenting them 5 spaces to the right of the current left
  1155. margin.  We might want to define the "command" as
  1156. "paragraph" [personally, I might call it "P", because it
  1157. would be used a lot and my typing ...]:
  1158.  
  1159. .de paragraph
  1160. .sp 1
  1161. .ne 2
  1162. .ti +5
  1163. .;;
  1164.  
  1165. Subsequently, whenever we wished to start a paragraph we
  1166. would creat a command line:
  1167.  
  1168. .paragraph
  1169.  
  1170. instead of more tediously creating every time the three
  1171. commands we mentioned above.
  1172.  
  1173.     The names of all commands, macros, strings, and number
  1174. registers are "case sensitive".  That is to say that
  1175. capitalization and/or lower case are distinguished and, say,
  1176.  
  1177. .Paragraph
  1178.  
  1179. Would not be recognized as the same sample macro we
  1180. just defined.  All the "built-in" commands, those
  1181. which were listed in the command table, are also case
  1182. sensitive and are recognized on the first two letters alone,
  1183. even if arbitrary letters or numbers follow immediately.
  1184. If we had a line:
  1185.  
  1186. .time
  1187.  
  1188. it would be identified with a "time" macro definition, if
  1189. one had been created;  It would not be confused with a
  1190. "Time" macro definition.  If there is no "time" macro, then
  1191. it would be matched with the "built-in", .ti ["Temporary
  1192. Indent"].  The important exception is that no macro or diversion
  1193. name should be used that could result in an invocation starting
  1194. as: .{, .}, .if, .ie, or .el;  these combinations are looked for
  1195. first before the macro table is checked.
  1196.  
  1197.     There is another object formed and used somewhat
  1198. like a macro;  it is called a "diversion" and is
  1199. useful for making lists such as references [or footnotes] and
  1200. tables of contents.  A diversion is created or continued
  1201. with the commands: .di [DIversion] and .da [Diversion Append].
  1202. To "regurgitate" the diversion, its name is used like one uses a
  1203. macro. In contrast to nroff, troff, ROFF5, v2.0 does NOT support
  1204. nesting of diversions; be sure to end a diversion before starting or
  1205. continuing another.
  1206.  
  1207.     Careful study of the file, "ma.", illustrates the use of
  1208. many of the macro techniques that we have found useful for document
  1209. preparation;  "ma.doc" provides a user's description of the macros.
  1210.  
  1211.     We shall present a detailed but simplified example of the
  1212. use  of the above preprocessing commands to automate reference
  1213. numbering and collection. 
  1214.  
  1215.     We start by creating a register variable, "r#", to
  1216. keep track of the current reference number:
  1217.  
  1218. .nr r# 1
  1219.  
  1220.     We shall use, say, "[15]" as our means to display
  1221. reference numbering.  (We could have used superscripts
  1222. instead with "^+15^-"):
  1223.  
  1224. .ds rn [\\r#\\]
  1225.  
  1226. We have used "\\" so that "rn" is defined as "[\r#\] and
  1227. will be evaluated with the current reference number at the
  1228. time of use (not of the time we made this .ds definition).
  1229. By typing \rn\ we will get the reference in the form,
  1230. "[number]", that we wanted.
  1231.  
  1232.     We want to create a diversion, "refs", into which
  1233. we will place all our references.  The head of this file
  1234. will be titled with "REFERENCES":
  1235.  
  1236. .di refs
  1237. .ls 1
  1238. .sp 1
  1239. .ce 1
  1240. REFERENCES
  1241. .sp 2
  1242. .di
  1243.  
  1244.     The diversion will contain (hopefully) a list of
  1245. numbered references.  To make the addition of these footnotes
  1246. as painless as possible, we define two macros, "RS"
  1247. [footnote start] and "RE" [footnote end]:
  1248.  
  1249. .de RS
  1250. .da refs
  1251. .sp 1
  1252. \\rn\\\\
  1253. .;;
  1254.     and:
  1255. .de RE
  1256. .di
  1257. .rg r# +1
  1258. .;;
  1259.  
  1260. The RS macro skips a line and attaches the evaluation of
  1261. \rn\ to the start of the line that follows the macro during
  1262. execution.  The lines that follow the RS macro will be
  1263. diverted to "refs".  The RE macro terminates the diversion
  1264. and, also, increments the reference number, r#.
  1265.  
  1266.     We could try a very small piece of text now:
  1267.  
  1268. .nf
  1269. It is a nice day.\rn\
  1270. .RS
  1271. conventional expression.
  1272. .RE
  1273. It's a crummy day.\rn\
  1274. .RS
  1275. unconventional!
  1276. .RE
  1277.  
  1278. The formatter will generate as immediate output:
  1279.  
  1280. It is a nice day.[1]
  1281. It is a crummy day.[2]
  1282.  
  1283. and it will place into the diversion, "refs":
  1284.  
  1285.  
  1286.  
  1287.              REFERENCES
  1288.  
  1289.  
  1290. [1]conventional expression.
  1291.  
  1292. [2]unconventional!
  1293.  
  1294.     --------------------------------
  1295.  
  1296. A series of files can be input using the .so ["SOurce"] command.
  1297. The advantage of using .so is that inclusion can be accomplished
  1298. without a page break, nor even a line break between input files.
  1299. The .so command is like a "CALL" or "GOSUB" in that there can be
  1300. nested .so invocations; one can access a file with .so that
  1301. contains in turn a .so command, etc.  It is a limitation of
  1302. ROFF5 at present to not be able to handle the .so command
  1303. from keyboard input (it could be useful).  The files,
  1304. SOTEST, ONE, TWO, and THREE are provided to test and
  1305. demonstrate the .so command.
  1306.  
  1307.     All file names referenced by .so are automatically treated
  1308. as uppercase.  The naming conventions should conform to the
  1309. operating system (CP/M or MS-DOS).  It is a potential limitation of
  1310. the formatter at present to not realize that "A:ZZ" would be the
  1311. same as "ZZ"; be sure to use the same form throughout!
  1312.  
  1313.     ------------------------------
  1314.